Skip to content

feat: Prometheus /metrics + TypeScript SDK + docs revamp#75

Merged
Gsbreddy merged 4 commits into
mainfrom
feat/prometheus-ts-sdk
Jun 1, 2026
Merged

feat: Prometheus /metrics + TypeScript SDK + docs revamp#75
Gsbreddy merged 4 commits into
mainfrom
feat/prometheus-ts-sdk

Conversation

@Gsbreddy
Copy link
Copy Markdown
Collaborator

@Gsbreddy Gsbreddy commented Jun 1, 2026

Summary

Three independently valuable additions in one PR:

1. Prometheus /metrics scrape endpoint

  • GET /metrics — standard text/plain; version=0.0.4 Prometheus exposition format
  • No new runtime dependencies — formatted manually
  • Same Bearer/loopback gate as GET /v1/metrics
  • Exposes: flightdeck_releases_total, flightdeck_run_events_total, flightdeck_promoted_pointers_total, flightdeck_actions_total, flightdeck_actions_by_type{action=}, flightdeck_pricing_tables_total, flightdeck_schema_version
  • 8 new tests, documented in docs/http-api.md with sample output + Prometheus scrape config YAML
  • Lights up Datadog, Grafana, Honeycomb, New Relic, Prometheus, VictoriaMetrics for free

2. TypeScript / Node.js SDK (sdk-ts/, package: flightdeck-ai)

  • FlightDeckClient: ingestEvent/s(), diff(), getWorkspace(), health() using native fetch (Node 18+, zero runtime deps)
  • FlightDeckOpenAIAdapter: wraps openai.chat.completions.create(), records tokens + latency + success as a RunEvent (fire-and-forget)
  • Types fully grounded in schemas/v1/run_event.schema.json and src/flightdeck/models.py
  • Retry on 429/5xx (3 attempts, exponential backoff). X-FlightDeck-Actor and X-Request-Id on every request
  • 584-line vitest suite covering auth, retry, diff parsing, adapter latency, cached tokens
  • Package name flightdeck-ai matches PyPI — npm install flightdeck-ai

3. MkDocs docs revamp (mkdocs build --strict passes)

  • docs/getting-started.md (NEW) — the "demo worked, now what?" bridge: 5 steps from real release registration to promotion with your actual agent
  • docs/index.md: "Where to start" decision table for first-time visitors
  • docs/cli.md: "Common patterns" section at top (4 copy-paste recipes)
  • docs/sdk.md: End-to-end quickstart example at top
  • docs/troubleshooting.md: "First 5 things to check" triage checklist
  • CHANGELOG: two blob links → hosted Pages URLs

Verification

  • ruff: clean
  • pytest --cov-fail-under=80: 210 passed / 4 skipped / 82.24% coverage (+8 Prometheus tests)
  • mkdocs build --strict: 0.33s, no warnings

Pre-merge checklist

  • Review sdk-ts/ — the TS SDK doesn't have a CI job yet (add npm ci && npm run typecheck && npm test to a new sdk-ts job in ci.yml if desired before publishing to npm)
  • Decide npm publish flow for flightdeck-ai on npm (separate workflow needed, similar to release-pypi.yml)
  • Smoke-test GET /metrics against a running flightdeck serve before tagging v1.4.0

Prometheus endpoint (no new dependencies):
- GET /metrics — standard text/plain; version=0.0.4 Prometheus scrape
  target. Exposes releases_total, run_events_total, promoted_pointers_
  total, actions_total, actions_by_type{action=}, pricing_tables_total,
  schema_version. Same Bearer/loopback gate as GET /v1/metrics.
  8 new tests in tests/test_prometheus_metrics.py.
  Documented in docs/http-api.md with sample output + scrape config.

TypeScript SDK (sdk-ts/, package name: flightdeck-ai):
- FlightDeckClient: ingestEvent/s(), diff(), getWorkspace(), health()
  using native fetch (Node 18+, zero deps).
- FlightDeckOpenAIAdapter: wraps openai.chat.completions.create(),
  records tokens + latency + success as a RunEvent. Fire-and-forget.
- Types fully grounded in schemas/v1/run_event.schema.json and
  src/flightdeck/models.py. No any casts except JSON deserialization.
- Retry on 429/5xx (3 attempts, exp backoff). X-FlightDeck-Actor and
  X-Request-Id headers on every request.
- 584-line vitest suite: auth, retry, diff parsing, adapter latency,
  cached tokens, fire-and-forget ingest errors.
- sdk-ts/README.md: install + 10-line quickstart + OpenAI snippet.
- Package name flightdeck-ai matches the PyPI package.

MkDocs docs revamp (--strict build passes, 0.33s):
- docs/getting-started.md (NEW): 'demo worked, now what?' — 5-step
  guide from real release registration through promotion. The page
  that was missing for first-time users.
- docs/index.md: 'Where to start' decision table (7 rows) above Quick
  reference.
- docs/cli.md: 'Common patterns' section at top (4 copy-paste recipes:
  register+diff, CI gate, weekly health, Slack webhook).
- docs/sdk.md: 'Quickstart' section at top (50-line annotated Python
  example, end-to-end).
- docs/troubleshooting.md: 'First 5 things to check' numbered checklist.
- mkdocs.yml: Getting started added as second nav item.

Link cleanup:
- CHANGELOG.md: two GitHub blob /docs/cli.md links → hosted Pages URL.
- All other relative links left intact (GitHub renders them correctly).
Comment thread sdk-ts/src/client.ts Fixed
Gsbreddy added 3 commits June 2, 2026 01:49
Three audiences kept hitting dead ends:
- 'I want to run this for my team' → no clear Postgres path
- 'Is SQLite OK for prod?' → no guidance
- 'How do I back up?' → pg_dump mention was buried

Changes:
- docs/getting-started.md: 'Production checklist' section — Postgres
  install (pip install 'flightdeck-ai[postgres]'), database_url YAML +
  env var, Bearer token for remote access, process supervisor guidance.
- docs/operations-and-policy.md: SQLite vs PostgreSQL summary table
  near the top, links to existing detailed section.
- docs/index.md: 'Deploy for a team in production' row added to the
  Where-to-start decision table.
- examples/deploy/README.md: 'Using PostgreSQL' section with a complete
  docker-compose.postgres.yml snippet (postgres:16-alpine + flightdeck
  wired via FLIGHTDECK_DATABASE_URL).
MAJOR-1: sdk-ts/package.json: peerDependenciesOptional -> peerDependenciesMeta
  peerDependenciesOptional is not a valid npm field (silently ignored,
  causes unmet peer dep warnings on every install). Replaced with the
  npm 7+ spec-compliant peerDependenciesMeta: { openai: { optional: true } }.

MAJOR-2: metrics.py: skip actions_by_type block when empty
  Prometheus text format 0.0.4 prohibits HELP/TYPE headers with zero
  time-series beneath them. Scraper warnings / rejections on fresh
  workspaces. Wrapped the block in 'if actions_by_action:'.

MAJOR-3: test_prometheus_metrics.py: tighten content-type assertion
  Was: 'text/plain' in content-type (too loose — any text/plain passes).
  Now: startswith('text/plain; version=0.0.4') to catch regressions in
  the full required header value.
CodeQL CWE-1333: /\/+$/ applied to user-supplied serverUrl flagged as
potential ReDoS. While /\/+$/ is linear in V8, CodeQL cannot statically
prove that and warns conservatively. Replaced with a plain while loop
that is provably O(n) and CodeQL-safe.
@Gsbreddy Gsbreddy marked this pull request as ready for review June 1, 2026 23:54
@Gsbreddy Gsbreddy merged commit afbd0fd into main Jun 1, 2026
13 checks passed
@Gsbreddy Gsbreddy deleted the feat/prometheus-ts-sdk branch June 1, 2026 23:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants